---
title: "@unkey/nextjs"
description: "Next.js SDK for Unkey"
---

The official Next.js SDK for Unkey. Use this within your [route handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers) as a simple, type-safe way to verify API keys.

<Card
  icon="github"
  title="github.com/unkeyed/sdks/tree/main/nextjs"
  href="https://github.com/unkeyed/sdks/tree/main/nextjs"
/>

## Install

<CodeGroup>

```bash npm
 npm install @unkey/nextjs
```

```bash pnpm
 pnpm add @unkey/nextjs
```

```bash yarn
 yarn add @unkey/nextjs
```

```bash bun
 bun add @unkey/nextjs
```

</CodeGroup>

Protecting API routes is as simple as wrapping them with the `withUnkey` handler:

```ts
import { NextRequestWithUnkeyContext, withUnkey } from "@unkey/nextjs";

export const POST = withUnkey(
  async (req: NextRequestWithUnkeyContext) => {
    // Process the request here
    // You have access to the verification response using `req.unkey`
    console.log(req.unkey);

    return new Response("Your API key is valid!");
  },
  { rootKey: process.env.UNKEY_ROOT_KEY! }
);
);
```

If you want to customize how `withUnkey` processes incoming requests, you can do so as follows:

### `getKey`

By default, withUnkey will look for a bearer token located in the `authorization` header. If you want to customize this, you can do so by passing a getter
in the configuration object:

```ts
export const GET = withUnkey(
  async (req) => {
    // ...
  },
  {
    rootKey: process.env.UNKEY_ROOT_KEY!,
    getKey: (req) => new URL(req.url).searchParams.get("key"),
  }
```

### `onError`

You can specify custom error handling. By default errors will be logged to the console, and `withUnkey` will return a NextResponse with status 500.

```ts
export const GET = withUnkey(
  async (req) => {
    // ...
  },
  {
    rootKey: process.env.UNKEY_ROOT_KEY!,
    onError: async (req, res) => {
      await analytics.trackEvent(`Error ${res.code}: ${res.message}`);
      return new NextResponse("Unkey error", { status: 500 });
    },
  }
);
```

### `handleInvalidKey`

Specify what to do if Unkey reports that your key is invalid.

```ts
export const GET = withUnkey(
  async (req) => {
    // ...
  },
  {
    rootKey: process.env.UNKEY_ROOT_KEY!,
    handleInvalidKey: (req, res) => {
      return new Response("Unauthorized", { status: 401 });
    },
  }
);
```
